ZBuilder
ZBuilder Software

ZBuilder Software provide’s custom programming services in addition to our line of C++ Builder components.

The software professionals of ZBuilder Software provide software services for a variety of platforms from Fortune 500 companies to the corner store.

Whether you need a compete solution, a small module, or just have a question, we can fulfill your needs.

E-Mail zbuilder@aol.com for additional information.

ZComm License Information


ZComm License

The ZComm component is being made available in two forms:

1. 	The evaluation/personal only version. This version may be downloaded from our Web Site. It may not be used for commercial purposes, nor sold directly or indirectly. The component itself may not be distributed unless it is complete(zcomm.zip) as downloaded from our web site.

1. 	Purchased version. A fully distributable version with source code may be purchased. The source code version will only be available once the beta period completes. Source code, access to Email support and a full license to distribute the component may be purchased.

Please see our Web site for additional details and availability.

http://members.aol.com/zbuilder

E-Mail us at zbuilder@aol.com


Overview

The ZComm component will allow access to serial ports from a high-level component interface.

Use the properties supplied to set the serial parameters BaudRate, Port, Parity, DataBits, StopBits, FlowCtl, setup the event OnDataAvailable and then call the method OpenConnection.


Methods

OpenConnection

SetConnection

CloseConnection

WriteComm

WriteCommByte

ReadComm

SetTimeouts

GetTimeouts

EscapeComm

PurgeCommPort


Properties

Text

Port

BaudRate

Parity

DataBits

StopBits

MaxReadLength

InputQueueSize

OutputQueueSize

XOnLimit

XOffLimit

CTSFlowCtl

DSRFlowCtl

EnableParity

DSRSensitive

TXResume

XOuputFlowCtl

XInputFlowCtl

ErrorReplace

DiscardNULL

AbortOnError

ErrorChar

XOnChar

XOffChar

TimeoutReadInterval

TimeoutReadMultiplier

TimeoutReadConstant

TimeoutWriteMultiplier

TimeoutWriteConstant

Read Only Properties

State

Version

Connected


Events

OnDataAvailable

OnErrorOccurred


OpenConnection

Use

Call this method after setting your serial properties and setting a OnDataAvailable event.

Will open the serial port.

Input

The serial properties

Return

True if open success

False if open failed

Example

ZComm1->OpenConnection();


SetConnection

Use

Used to change the serial port parameters.

 Called by OpenConnection.

Input

The various serial properties.

Return

True on success, False on failure

Example

ZComm1->SetConnection();


CloseConnection

Use

Closes an open serial connection.

Input

None

Return

True on success, False on failure

Example

ZComm1->CloseConnection();


WriteComm

Use

This method is used to send binary data to the serial connection.

Note: to send non-binary data you may use the Text property.

Input

unsigned char 	buffer	pointer to data

long	length	length to send

Return

True on success, False on failure

Example

char	buffer[256];

strcpy(buffer, “This is a test”);

ZComm1->WriteBlock(buffer, strlen(buffer));


WriteCommByte

Use

Sends a single character to the serial connection.

Input

char	the character to send

Return

True on success, False on failure

Example

unsigned char	c;

ZComm1->WriteCommByte(c);


ReadComm

Use

Will return the available data from the serial port, used when the event OnDataAvailable is triggered.

Note: This method is used for binary data. You may use the Text property to receive non-binary data.

Input

buffer	pointer to area to place received data

length	maximum data to receive

Return

True on success, False on failure

Example

char *buffer;

buffer = GlobalAlloc(GPTR, 100);

if (buffer) ZComm1->ReadComm(buffer, 100);

else ...memory error...


SetCommTimeouts
SetTimeouts

 Use

This method will set the port timeouts for the current port to the values stored in the Timeout properties.

Input

The properties:

TimeoutReadInterval

TimeoutReadMultiplier

TimeoutReadConstant

TimeoutWriteMultiplier

TimeoutWriteConstant

Return

True if success, false on error

Example

result = ZComm1->SetTimeouts();


GetCommTimeouts
GetTimeouts

Use

Will set the timeout properties to the values of the current port.

The properties set:

TimeoutReadInterval

TimeoutReadMultiplier

TimeoutReadConstant

TimeoutWriteMultiplier

TimeoutWriteConstant

Input

None

Return

True on success, false on failure

Example

result = ZComm1->GetTimeouts();


EscapeComm

Use

The EscapeCommFunction function directs a specified communications device to perform an extended function.

The param specifies the code of the extended function to perform. This parameter can be one of the following values:

Value	Meaning

CLRDTR	Clears the DTR (data-terminal-ready) signal.

CLRRTS	Clears the RTS (request-to-send) signal.

SETDTR	Sends the DTR (data-terminal-ready) signal.

SETRTS	Sends the RTS (request-to-send) signal.

SETXOFF

Causes transmission to act as if an XOFF character has been received.

SETXON

Causes transmission to act as if an XON character has been received.

SETBREAK

Suspends character transmission and places the transmission line in a break state until the ClearCommBreak function is called (or EscapeCommFunction is called with the CLRBREAK extended function code). The SETBREAK extended function code is identical to the SetCommBreak function. Note that this extended function does not flush data that has not been transmitted.

CLRBREAK

Restores character transmission and places the transmission line in a nonbreak state. The CLRBREAK extended function code is identical to the ClearCommBreak function.

Input

unsigned long param

Return

True on success, false on failure

Example

result = ZComm1->EscapeComm(SETDTR);


PurgeCommPort

Use

Clears the input and output buffers and/or terminates the io events of the current comm port.

Input

unsigned long action

Specifies the action to take. This parameter can be a combination of the following values:

Value	Meaning

PURGE_TXABORT

Terminates all outstanding write operations and returns immediately, even if the write operations have not been completed.

PURGE_RXABORT

Terminates all outstanding read operations and returns immediately, even if the read operations have not been completed.

PURGE_TXCLEAR

Clears the output buffer (if the device driver has one).

PURGE_RXCLEAR

Clears the input buffer (if the device driver has one).

Return

True on success, false on failure

Example

result = ZComm1->PurgeComm(PURGE_TXCLEAR);


Text

Description

This property is used to send or receive non-binary data from a serial connection.

Note: Since this property is a zero-terminated AnsiString you may not receive data that contains zero byte values.

Type

AnsiString


Port

Description

This is the serial port that the ZComm component will connect to.

Com1, Com2 ...

Type

AnsiString


BaudRate

Description

The Baud Rate that the serial connection will be made at

110 	19200

300 	38400

600 	56000

1200	57600

2400	115200

4800	128000

9600	256000

14400

OR any valid baud rate

Type

AnsiString


Parity

Description

The parity of the serial connection

One of the following values:

no_parity, odd_parity, even_parity, mark_parity, space_parity

Note: some databits/parity/stopbits combinations are invalid

Type

int (TParity)


DataBits

Description

The number of databits for the serial connection

One of the following values:

databits4, databits5, databits6, databits7, databits8

Note: some databits/parity/stopbits combinations are invalid

Type

int (TDataBits)


StopBits

Description

The number of stop bits for the serial connection

One of the following values:

stop1, stop1x5, stop2

Note: some databits/parity/stopbits combinations are invalid

Type

unsigned int


MaxReadLength

Description

The maximum size that the Text property may return.

The default size is 8192

Type

long


InputQueueSize

Description

The size in bytes of the serial input queue.

The default size is 8192

Type

unsigned long


OutputQueueSize

Description

The size in bytes of the serial output queue.

The default size is 8192

Type

unsigned long


XOnLimit

Description

Specifies the minimum number of bytes allowed in the input buffer before the XON character is sent.

Type

int


XOffLimit

Description

Specifies the maximum number of bytes allowed in the input buffer before the XOFF character is sent. The maximum number of bytes allowed is calculated by subtracting this value from the size, in bytes, of the input buffer.

Type

int


CTSFlowCtl

Description

Specifies whether the CTS (clear-to-send) signal is monitored for output flow control. If this property is TRUE and CTS is turned off, output is suspended until the CTS signal is high.

Type

Boolean


DSRFlowCtl

Description

Specifies whether the DSR (data-set-ready) signal is monitored for output flow control. If this property is TRUE and the DSR is low, output is suspended until the DSR signal is asserted.

Type

int


EnableParity

Description

Specifies whether parity checking is enabled. This property if TRUE, causes parity checking to be performed and errors are reported.

Type

Boolean


DSRSensitive

Description

Specifies whether the ZComm component is sensitive to the state of the DSR signal. If this property is TRUE, the component ignores any bytes received, unless the DSR signal is high.

Type

Boolean


TXResume

Description

Specifies whether transmission stops when the input buffer is full and the component has transmitted the XoffChar character. If this property is TRUE, transmission continues after the input buffer has come within XoffLim bytes of being full and the component has transmitted the XoffChar character to stop receiving bytes. If this property is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the component has transmitted the XonChar character to resume reception.

Type

Boolean


XOuputFlowCtl

Description

Specifies whether XON/XOFF flow control is used during transmission. If this property is TRUE, transmission stops when the XoffChar character is received and starts again when the XonChar character is received.

Type

Boolean


XInputFlowCtl

Description

Specifies whether XON/XOFF flow control is used during reception. If this property is TRUE, the XoffChar character is sent when the input buffer comes within XoffLim bytes of being full, and the XonChar character is sent when the input buffer comes within XonLim bytes of being empty.

Type

Boolean


ErrorReplace

Description

Specifies whether bytes received with parity errors are replaced with the character specified by the ErrorChar member. If this property is TRUE and the Parity property is TRUE, replacement occurs.

Type

Boolean


DiscardNULL

Description

Specifies whether null bytes are discarded. If this property is TRUE all null bytes are discarded when received.

Type

Boolean


AbortOnError

Description

This property specifies whether read and write operations are terminated if an error occurs. If this property is TRUE, the component terminates all read and write operations with an error status if an error occurs. The component will not accept any further communications operations until the application has acknowledged the error by calling the ClearCommError function.

Type

Boolean


ErrorChar

Description

Specifies whether bytes received with parity errors are replaced with the character specified by the ErrorChar property. If this property is TRUE and the Parity property is TRUE, replacement occurs.

Type

Boolean


XOnChar

Description

Specifies the value of the XON character for both transmission and reception.

Type

char


XOffChar

Description

Specifies the value of the XOFF character for both transmission and reception.

Type

char


TimeoutReadInterval

Description

Specifies the maximum time, in milliseconds, allowed to elapse between the arrival of two characters on the communications line. During a ReadFile operation, the time period begins when the first character is received. If the interval between the arrival of any two characters exceeds this amount, the ReadFile operation is completed and any buffered data is returned. A value of zero indicates that interval time-outs are not used. A value of MAXDWORD, combined with zero values for both the TimeoutReadConstant and TimeoutReadMultiplier members, specifies that the read operation is to return immediately with the characters that have already been received, even if no characters have been received.

A value of 5000 == 5 seconds, 1000 = 1 second, etc...

Type

unsigned long


TimeoutReadMultiplier

Description

Specifies the multiplier, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is multiplied by the requested number of bytes to be read.

A value of 5000 == 5 seconds, 1000 = 1 second, etc...

Type

unsigned long


TimeoutReadConstant

Description

Specifies the constant, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is added to the product of the TimeoutReadMultiplier property and the requested number of bytes.

A value of zero for both the TimeoutReadMultiplier and TimeoutReadConstant members indicates that total time-outs are not used for read operations.

A value of 5000 == 5 seconds, 1000 = 1 second, etc...

Type

unsigned long


TimeoutWriteMultiplier

Description

Specifies the multiplier, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is multiplied by the number of bytes to be written.

A value of 5000 == 5 seconds, 1000 = 1 second, etc...

Type

unsigned long


TimeoutWriteConstant

Description

Specifies the constant, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is added to the product of the TimeoutWriteMultiplier property and the number of bytes to be written.

A value of zero for both the TimeoutWriteMultiplier and TimeoutWriteConstant properties indicates that total time-outs are not used for write operations.

A value of 5000 == 5 seconds, 1000 = 1 second, etc...

Type

unsigned long


State

Description

The current state of the component

Type

int


Version

Description	READ ONLY

The current version of the ZComm Component

Type

AnsiString


Connected

Description

The connection state of the ZComm component

Type

BOOL


OnErrorOccurred

Trigger

The ZComm component generates this event when an error that it is not able to handle occurs.


OnDataAvailable

Trigger

This event is generated when data is available to be read from the serial port.